Multiprocessing is the use of more than one processor (CPU) simultaneously. By definition only a machine with more than one CPU is capable of multiprocessing. Multitasking allows multiple streams of execution to be created even if there is only a single CPU. The MP API implements a multiprocessing, multitasking environment. Any number of streams of execution can be created and one stream per CPU can be executing at any particular instant in time. Each stream of execution is called a task. Having concurrent tasks working on parts of some job, e.g. a ray trace, an image filter, a fractal etc., can reduce the overall time it takes to complete the job.
What is the MP API?
The MP API allows a programmer to create tasks and to establish communication between them and the main application. A small number of other services are also available. The MP API document describes these services in detail.
What is the Multiprocessing API Library?
The Multiprocessing API Library is a shared library that provides the services defined in the MP API. The Multiprocessing API Library also manages task scheduling and other task related issues. The Multiprocessing API Library and its associated files are usually installed in the extensions folder. Storing the Multiprocessing API Library in a subfolder within the extensions folder is recommended since this can reduce the amount of time required to launch MP-aware applications.
What is a good way to install the library for development purposes?
Instead of putting the library into the extensions folder take the whole Multiprocessing folder and put it into your ':MacOS Support:Headers:System Extras Headers:' folder. If you are not using Metrowerks use whatever the equivalent folder in your development environment is. Make an alias to the Multiprocessing API Library and put it into your extensions folder. The Multiprocessing API Library and the MP.h file should now be available to your projects in their standard search paths and since the Code Fragment Manager knows how to resolve aliases the Multiprocessing API Library will be available on a system wide basis. Note that extensions will not be able to connect to the Multiprocessing API Library unless it resides on the same volume as the System Folder -this includes the MetroNub debugging extension from Metrowerks so be careful about this.
What can tasks do?
In general tasks can execute any function accessable by your application. Tasks created using the MP API provided on this SDK have the ability to access main memory and to communicate with other tasks as well as the application. Tasks must adhere to the restrictions outlined below.
What are the restrictions on tasks and the application?
Tasks must not execute 68k code.
Tasks may not call the Macintosh Toolbox.
The application may not make MP API calls at interrupt time or from within a deferred task. However, there are safe techniques available for communicating with tasks at these times. Note that deferred tasks are defined in the Deferred Task Manager, they are not an MP API related concept.
How are tasks run?
Tasks are inserted into a scheduling queue and are assigned to available processors. Tasks run preemptively. They run for a certain amount of time after which they will be interrupted and returned to the end of the scheduling queue. This way all tasks in the system can be assured fair access to the available processors. Tasks can also voluntarily return themselves to the scheduling queue using the MPYield() call. When a task blocks on one of the communication primitives, and that primitive is not available, the task is immediately suspended and the next task on the scheduling queue is run. Suspended tasks are not returned to the scheduling queue until the primitive on which they are waiting becomes available. Suspended tasks incur no system overhead.
How many tasks should I create?
The number of tasks an application can create is not logically limited. Most applications will want to limit the creation of tasks that perform a given function to the number of available processors. As long as there are at least as many tasks performing work as there are available processors, maximum advantage of the system will be taken. Some problems are best decomposed into a fixed number of tasks, regardless of the number of processors. It is sometimes useful to have the main application perform some of the work also. This is especially true in applications that do not require the Multiprocessing API Library to be present. In this case the optimum number of tasks to create is one less than the number of processors.
Do I need a multiprocessing system to use the MP API?
No. If the Multiprocessing API Library is available so are all of its services. This means that you can create preemptive tasks on a PowerPC platform, provided those tasks adhere to the restrictions described above.
What special tools do I need for development?
You continue to use the same development tools you have always used. There are no special compilers or linkers to be used. All you add is a header file, MP.h, as well as the Multiprocessing API Library.
How do I debug this stuff?
DayStar and Apple are working together to provide debugging tools. In addition, Metrowerks will be providing MP debugging support within CodeWarrior 9. Anything that can be done in the current Metrowerks debugging environment within applications should also be possible within tasks. The MetroNub debugger extension must have the size specified in its 'sysz' resource increased to 2 580 000
bytes. Use ResEdit or Resourcer to do this. MetroNub requires the Multiprocessing API Library, i.e, the library or an alias to the library should be in the Extensions folder at startup.
How can I test MP-savvy applications?
Apple and DayStar recommend testing the MP-savvy applications on two platforms: a uniprocessor Macintosh and a multiprocessor Macintosh. The application code can be identical in both cases, but the application may have dependencies or race conditions that are only visible on a multiprocessor system.
When can I get started?
You can start now. The Multiprocessing API Library included on this disk is the final product. It will allow you to create and test applications on uniprocessor systems that will run without modification on real multiprocessing systems (assuming no programming errors of course).
When will hardware be available?
Hardware is available from DayStar now. Apple has also announced their intention to deliver multiprocessing systems in the 4th quarter of 1996. Contact DayStar at the address below for information regarding developer pricing.
How will supporting the MP API impact my source base? What about 68K?
The MP API cannot be used on 68k machines. You can have a single source base but the 68k side will never be able to create multiprocessing tasks -it should behave as though the Multiprocessing API Library is not present. The PPC side should also be able to handle the situation where the Multiprocessing API Library is not present. The same code can thus be used for both situations.
If an application requires PPC and is also willing to require the presence of the Multiprocessing API Library, then tasks can be created and executed regardless of the number of processors in the system. Tasks created by an application are distributed preemptively amongst the available processors, even if there is only one, so task-creating code will work on any type of PPC system -multiprocessing or not.
What will happen to the MP API when Copland (System 8) ships?
The MP API will run on all current and planned generations of the PowerPC-based Mac OS—namely, System 7, Copland, and Gershwin.
How are the MP API and the Thread Manager related?
MP tasks are a System 7 placeholder for Copland tasks (not threads), and will become kernel tasks in future SMP versions of MacOS. The task and thread APIs will remain different.
The Thread Manager API will definitely be supported in Copland, but there are no plans to extend it. Threads will continue to have the same cooperative scheduling model in Copland that they do today in System 7. Threads are not the path to preemptive scheduling or multiprocessor support in Copland.
We are recommending that developers use the MP API to write apps that wish to take advantage of preemptive scheduling and multiprocessors, both on System 7 and Copland. This API will be fully supported in System 7, Copland, and beyond. It has been designed to map naturally into the Copland tasking model. In future SMP-capable versions of MacOS, MP tasks will become identical to kernel tasks, at which time the MP APIs will become thin layers of glue mapping them into kernel calls. The "MP" API is probably misnamed, because it will be supported on all Power Macintosh systems, both uniprocessor and multiprocessor. An app written to the MP API will automatically take advantage of all CPUs that are available. On uniprocessor systems, MP tasks behave like preemptive tasks.
How should my application exploit multiprocessing?
This question is handled in detail in the document 'MacTech Article' included on this SDK.
Where can I find examples?
Example code is provided in the 'Sample Code' folder on this SDK.
How can I communicate with a task at interrupt time or from within a deferred task?
Communication can be achieved by writing to a pre-agreed trigger location. A task can repeatedly poll this trigger until it changes. It is advisable to immediately precede all writes to the trigger with a call to __eieio(), especially if earlier changes to memory that the polling task requires have been made. This ensures that the earlier changes are really made before the trigger is set -PowerPCs do not necessarily write data to memory in the order requested. The task can call MPYield() while looping on the trigger which will ensure that it relinquishes the CPU while the trigger is not available.
When the task is done it can issue an __eieio() and write to a trigger that the application is waiting on. If the application loops on the trigger be sure to remember NOT to call MPYield(). The Multiprocessing API Library is not interrupt safe and any attempt to call it at interrupt time or deferred task time will potentially cause a crash.
Never use this technique if you are writing a normal application.
What kind of problems can I expect from tasks sharing memory?
Tasks should be careful about what memory they modify -it is not polite to modify memory being used by another task without communicating that fact to the other task. Modifying globals from within a task, or buffers pointed to by global variables should be avoided.
I crash after calling MPTerminateTask(). Why?
MPTerminateTask() does not terminate a running task immediately. The task continues to run until it is preempted at which time it is terminated. Normal application cleanup techniques involve terminating the tasks and then disposing of all the semaphores, queues, memory, etc that the tasks were using. Unfortunately since the task doesn't really stop running straight away it starts using invalid data as the application starts deleting the shared resources. This can lead to catastrophic crashes. The best way to avoid this situation is to provide a termination queue when you create a task, and wait on the queue immediately after terminating the task. Once something is received you can be sure that the task is no longer running. Alternatively your application can notify a task that it is about to be terminated and wait for the task to acknowledge the notification. The task should not use any more shared resources after it sends the acknowledgement.
How do I get support for the MP API?
DayStar Digital is providing developer services for the MP API. You can contact MP developer support at mp@daystar.com or call (770) 967 2077 x267. Other information is available on DayStar's World Wide Web Home Page (http://www.daystar.com).
